//+------------------------------------------------------------------+
//|                                                    SignalITF.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include <Expert/ExpertSignal.h>    // 专家顾问信号基类（提供信号生成框架）

// wizard description start（MQL5 策略向导描述，用于识别类信息与参数）
//+------------------------------------------------------------------+
//| 类功能描述                                                       |
//| Title=基于日内时间过滤器（Intraday Time Filter）的交易信号         |
//| Type=SignalAdvanced                                              |
//| Name=IntradayTimeFilter                                          |
//| ShortName=ITF                                                    |
//| Class=CSignalITF                                                 |
//| Page=signal_time_filter                                          |
//| Parameter=GoodHourOfDay,int,-1,优质小时（允许交易的特定小时，-1=不限制）|
//| Parameter=BadHoursOfDay,int,0,劣质小时（禁止交易的小时位图，二进制位表示）|
//| Parameter=GoodDayOfWeek,int,-1,优质星期（允许交易的特定星期，-1=不限制）|
//| Parameter=BadDaysOfWeek,int,0,劣质星期（禁止交易的星期位图，二进制位表示）|
//+------------------------------------------------------------------+
// wizard description end

//+------------------------------------------------------------------+
//| CSignalITF 类：基于日内时间过滤器的交易信号生成器                  |
//| 核心能力：继承自 CExpertSignal，通过设置“允许/禁止交易的时间规则”（分钟、小时、星期）， |
//|           过滤非交易时段的信号，仅在符合时间条件时允许策略执行交易，提升策略有效性 |
//| 核心逻辑：通过“优质时间”（必须满足）和“劣质时间”（必须排除）的双重过滤， |
//|           结合当前时间判断是否符合交易条件，返回过滤结果（符合=0.0，不符合=无效值） |
//| 适用场景：所有受时间影响的交易策略（如特定时段波动大/小、流动性高/低的品种）， |
//|           例如外汇欧洲盘/美盘、股票早盘/尾盘、加密货币特定时段活跃期等         |
//+------------------------------------------------------------------+
class CSignalITF : public CExpertSignal
  {
protected:
   // 时间过滤参数（保护，子类可访问）
   int               m_good_minute_of_hour;  // 优质分钟（允许交易的特定分钟，-1=不限制）
   long              m_bad_minutes_of_hour;  // 劣质分钟（禁止交易的分钟位图，二进制位表示，如1<<30=禁止30分）
   int               m_good_hour_of_day;     // 优质小时（允许交易的特定小时，-1=不限制）
   int               m_bad_hours_of_day;     // 劣质小时（禁止交易的小时位图，二进制位表示，如1<<15=禁止15点）
   int               m_good_day_of_week;     // 优质星期（允许交易的特定星期，-1=不限制，0=周日，1=周一...5=周五，6=周六）
   int               m_bad_days_of_week;     // 劣质星期（禁止交易的星期位图，二进制位表示，如1<<5=禁止周五）

public:
   //----------------------------------------------------------------
   // 构造与析构函数
   //----------------------------------------------------------------
   /**
    * @brief 构造函数：初始化日内时间过滤器
    * @details 1. 初始化所有时间过滤参数为默认值（优质时间=-1=不限制，劣质时间=0=无禁止）；
    *          2. 默认允许所有时间交易，需通过外部接口设置具体过滤规则；
    *          3. 继承父类 CExpertSignal 的信号框架初始化
    */
                     CSignalITF(void);

   /**
    * @brief 析构函数：清理日内时间过滤器资源
    * @details 释放时间参数占用的内存，依赖父类析构逻辑完成信号框架资源清理
    */
                    ~CSignalITF(void);

   //----------------------------------------------------------------
   // 时间过滤参数配置：设置允许/禁止交易的时间规则（外部调用接口）
   //----------------------------------------------------------------
   /**
    * @brief 设置优质分钟（仅允许指定分钟交易）
    * @param value [in] 分钟值（0-59，-1=不限制，如30=仅允许30分所在K线交易）
    */
   void              GoodMinuteOfHour(int value);

   /**
    * @brief 设置劣质分钟（禁止指定分钟交易）
    * @param value [in] 分钟位图（二进制位表示，如1<<15=禁止15分，1<<30 | 1<<45=禁止30分和45分）
    */
   void              BadMinutesOfHour(long value);

   /**
    * @brief 设置优质小时（仅允许指定小时交易）
    * @param value [in] 小时值（0-23，-1=不限制，如15=仅允许15点所在K线交易）
    */
   void              GoodHourOfDay(int value);

   /**
    * @brief 设置劣质小时（禁止指定小时交易）
    * @param value [in] 小时位图（二进制位表示，如1<<3=禁止3点，1<<9 | 1<<18=禁止9点和18点）
    */
   void              BadHoursOfDay(int value);

   /**
    * @brief 设置优质星期（仅允许指定星期几交易）
    * @param value [in] 星期值（0=周日，1=周一...5=周五，6=周六，-1=不限制，如1=仅允许周一交易）
    */
   void              GoodDayOfWeek(int value);

   /**
    * @brief 设置劣质星期（禁止指定星期几交易）
    * @param value [in] 星期位图（二进制位表示，如1<<6=禁止周六，1<<0 | 1<<6=禁止周日和周六）
    */
   void              BadDaysOfWeek(int value);

   //----------------------------------------------------------------
   // 时间过滤核心方法：判断当前时间是否符合交易条件（策略决策依据）
   //----------------------------------------------------------------
   /**
    * @brief 检查当前时间是否在允许交易的时间范围内，返回过滤结果
    * @return double - 过滤结果：0.0=符合时间条件（允许交易），EMPTY_VALUE=不符合（禁止交易）
    * @note 核心判断逻辑（优先级：星期 → 小时 → 分钟，逐层过滤）：
    *       1. 星期检查：必须是优质星期（或不限制），且不在劣质星期位图中；
    *       2. 小时检查：必须是优质小时（或不限制），且不在劣质小时位图中；
    *       3. 分钟检查：必须是优质分钟（或不限制），且不在劣质分钟位图中；
    *       4. 所有条件均满足返回0.0（允许交易），任意条件不满足返回EMPTY_VALUE（禁止交易）；
    *       5. 与其他信号叠加时，若返回EMPTY_VALUE，策略将忽略当前所有交易信号
    */
   virtual double    Direction(void);
  };
//+------------------------------------------------------------------+